Modernizing a legacy front-end application is a high-leverage initiative for improving developer experience, scaling product capabilities, and aligning with today’s front-end ecosystem. But a full rewrite often introduces more risk than reward—especially in large-scale systems.

In this article, I outline a practical, battle-tested migration strategy that enables gradual, low-risk adoption of a modern Next.js architecture. The focus is on coexistence, reuse, and controlled transformation—so your teams can continue shipping features without disruption.

This is a follow-up to my previous article, Designing a Scalable Architecture for Next.js Applications, which covers how to structure your Next.js codebase for scalability, autonomy, and reuse. If you’re tackling both architecture and migration, I recommend reading them together.

Why Migrate at All?

Most legacy front-end applications eventually hit structural and productivity ceilings:

• Slow builds and feedback loops
• Poor TypeScript support and toolchain fragmentation
• Limited ecosystem or community support
• Difficulty hiring engineers who are excited to work with outdated stacks
• Friction in adopting modern patterns like modular architectures, proper state management, or composable UIs

Migrating to Next.js brings you closer to a modern development experience, improved performance characteristics, and access to a mature ecosystem. But it's not just about rewriting code—it's about rethinking how the front-end is structured, owned, deployed, and evolved.

Key Migration Principles

1. Think in Phases, Not Big Bangs

A full rewrite is rarely feasible for large applications. Instead, split the migration into clearly defined phases:

• Foundation Setup: Introduce shared tooling and architecture (linting, formatting, design systems)
• First Integration: Build and ship an isolated page in Next.js
• Parallel Adoption: Scale migration across teams or features
• Decommission Legacy: Retire remaining legacy routes and tooling

2. Use Route-Based Isolation with a Reverse Proxy

One of the most powerful strategies for incremental migration is to delegate routing between applications using a reverse proxy. This allows you to serve parts of your front-end from the legacy app and other parts from the Next.js app, without merging their build systems or runtimes.

How It Works:

• You configure a reverse proxy (e.g., Nginx, Vercel Middleware, Traefik) to route paths to different applications.
• Each app is deployed independently—on separate sub-directories (e.g., /app and /admin).
• On navigation, the proxy decides whether to serve the request from the legacy or the modern app.

This setup allows users to interact with both parts of the application as if it were a single unified app—while maintaining complete separation of build tools, deployment processes, and runtime contexts.

Key Benefits:

• No bundler conflicts: Each app builds independently.
• Full isolation: No shared global state; fewer regressions.
• Independent deployments: You can ship updates to the modern app without touching the legacy one.
• Scalability: Enables gradual adoption across routes or teams.

Key Considerations:

• Cross-app navigation requires full page reloads.
• Authentication/session state must be synchronized (e.g., via cookies).
• Visual consistency is critical—use a shared component library and design tokens.
• Preview environments must replicate proxy behavior for proper QA.

3. Build a Shared Component Library

To avoid fragmented UI and duplicate logic, centralize your UI into a framework-agnostic component library. Components like buttons, navigation bars, modals, and forms should be reused across both the legacy and Next.js apps.

Benefits include:

• Visual and behavioral consistency
• Faster migration (less to rewrite)
• One source of truth for accessibility and theming

4. Create a Link Strategy

Navigation across apps must be handled gracefully. A robust and non-invasive solution is to override window.history.pushState and window.history.replaceState globally.

Why this works:

• Transparent: No need to update every link or navigation helper
• Consistent: Applies the same logic to all navigations across the app
• Backward-compatible: Doesn’t break existing internal routing logic

How to implement:

In your app's bootstrap file (early in the lifecycle), inject the following override:

const originalPushState = window.history.pushState;
const originalReplaceState = window.history.replaceState;

function determineApp(url) {
	return url.startsWith('/app') ? "legacy" : "next.js";
}

function isCrossAppNavigation(newUrl) {
	const currentUrl = window.location.href;
	const currentApp = determineApp(currentUrl);
	const newApp = determineApp(newUrl);
	return newApp !== currentApp;
}

function interceptNavigation(method, url) {
  if (isCrossAppNavigation(url)) {
    window.location.href = url; // Trigger full reload for cross-app routes
  } else {
    method.apply(window.history, arguments); // Normal SPA routing
  }
}

window.history.pushState = function () {
  interceptNavigation(originalPushState, arguments[2]);
};

window.history.replaceState = function () {
  interceptNavigation(originalReplaceState, arguments[2]);
};

This logic ensures navigation between isolated apps behaves correctly behind a reverse proxy—without modifying every component.

5. Start with Low-Dependency Pages

Start with routes that:

• Have minimal global state requirements
• Don’t rely heavily on legacy modals, services, or inter-app communication
• Can be built quickly using the shared component library

This lets you build confidence in the new architecture before tackling deeply embedded routes.

6. Avoid Introducing New Legacy Code

Once the migration is underway:

• Treat the legacy app as “read-only”
• Direct all new feature work into the Next.js app
• Migrate existing shared logic into framework-agnostic packages when possible

7. Align Teams Around Shared Ownership

Move from a gatekeeper model (one team owns all shared tools) to a custodianship model:

• All teams can contribute
• Core maintainers uphold consistency and review PRs

This decentralizes velocity and enables scale.

8. Invest in Developer Enablement

Equip engineers to succeed in the new architecture by:

• Offering hands-on training (Next.js, modular React, shared components)
• Documenting patterns and standards
• Hosting internal workshops or pairing sessions

Architecture Good-to-Haves

A strong architectural foundation is essential for a smooth and scalable migration process. During your transition, adopt the following good practices:

• Separation of concerns across layout, logic, and data
• Preview environments per branch to validate changes visually and functionally before merging
• Shared tooling and design system to enforce consistency and reduce duplication
• Comprehensive testing strategy including unit, integration, E2E, and visual regression coverage

For a detailed breakdown of how to implement and scale these patterns, see Designing a Scalable Architecture for Next.js Applications.

Build a Proof of Concept

A successful migration to Next.js isn’t just about adopting a modern framework—it’s about ensuring it fits your application architecture, team workflows, and existing constraints.

A POC aims to:

• De-risk architectural decisions early
• Explore realistic co-existence between legacy and modern apps
• Validate routing, auth, state, and styling approaches
• Align engineering teams around workable patterns
• Reveal operational and developer experience trade-offs

🔍 Feature Summary: Next.js App

📌 Important Note: There is no one-size-fits-all solution. None of the tools mentioned above are strictly required—you can choose the one that best suits your specific needs.

🧪 What The POC Should Prove

We’re not proving if Next.js works—we’re proving if Next.js works for us, within our existing environment and constraints. Specifically:

1. Cross-App Routing via Reverse Proxy

• Confirm that the legacy app and Next.js can coexist behind a shared Nginx reverse proxy
• Validate navigation from the legacy app to Next.js (e.g., via window.location)
• Validate navigation from Next.js to the legacy app (e.g., via custom navigation logic)
• Ensure that deep linking, reloads, and history behavior work consistently

2. Authentication Consistency

• Ensure shared session tokens (cookies/headers) work across both apps
• Validate protected routes in Next.js using middleware.ts
• Achieve parity in auth behavior between the two apps

3. Shared Global Features

• Implement at least two shared UI features as framework-agnostic components (e.g., Web Components)
• Validate:
  • The components render correctly in both apps
  • Props are passed and events are emitted correctly
  • Compatibility with state management and i18n context

4. Modern State Management

• Replace one piece of the legacy state with Zustand
• Replace one chunk of the legacy API handling with TanStack Query + openapi-typescript
• Ensure:
  • Type safety
  • Composability
  • Clean sync/async state updates

5. Developer Experience & DevOps Flow

• Verify that both apps can run locally in a DevContainer with hot reload
• Confirm that adding new routes in Next.js is straightforward
• Check that preview deployments work via Vercel
• Make sure CI reliably runs both end-to-end and unit tests
• Ensure new developers can onboard without needing deep legacy knowledge

6. Minimum Feature Completeness

Deliver a small, production-ready “Hello World” feature that:

• Uses next-intl for translations
• Connects to a real API using TanStack Query
• Integrates a shared component
• Deploys automatically and is reachable via the reverse proxy

📡 Server State: TanStack Query + openapi-typescript

I recommend openapi-typescript to generate TypeScript-safe API contracts and TanStack Query for declarative data fetching. This ensures:

• Fully typed request/response payloads
• Automated caching, background updates, and error handling
• Strict API contract validation through type checking

🧠 Client State: Zustand

Zustand is my recommendation for global UI state, replacing legacy state management. It's:

• Minimal and performant
• Great for auth tokens, modals, theme toggles, etc.
• Free from context/provider boilerplate

Use TanStack Query for server data and Zustand for app-wide UI state.

🌐 Internationalization with next-intl

I recommend next-intl for fully type-safe, translation-ready setups.

Further Reading: Type-Safe i18n in Next.js: A Complete Guide

🔁 Shared Features: Strategy Options

Three ways to share global features across apps:

1. iFrame Embedding: Isolates features completely but comes with high overhead.
2. Framework-Agnostic Components (Recommended): Use Web Components or custom elements to maximize reuse while minimizing duplication.
3. Shared Logic Packages: Enables elegant integration across apps, but requires a higher upfront design investment.

🔐 Authentication Strategy

Implement auth in Next.js to match the legacy app, using:

• Shared cookies/headers
• middleware.ts for route-level protection
• Nginx proxy to preserve session and redirect logic

💻 Dev Environment Overview

• Fully containerized via Docker
• Reverse proxy (Nginx) bridges both apps
• DevContainer support in VS Code
• Enables seamless hot reload and unified routing

✅ POC Task Checklist

Setup

• |
  Initialize monorepo with apps/web
• |
  Apply base configurations such as linting and tsconfig
• |
  Set up DevContainer and Docker environment
• |
  Configure Vercel for deployment

Auth & Routing

• |
  Implement middleware.ts for route protection
• |
  Set up two-way navigation and proxy routing

Shared Features

• |
  Build one or two shared components (Web Component)
• |
  Validate compatibility across both apps

State & Data

• |
  Replace legacy state management + API handling with TanStack Query + Zustand
• |
  Generate API types via OpenAPI

Testing

• |
  Add unit tests with Vitest
• |
  Add e2e tests with Cypress or Playwright
• |
  Configure GitHub Actions to run all tests

By delivering this POC, you’ll validate the technical feasibility and developer experience of a gradual migration to Next.js—without betting the farm. You’ll walk away with clear learnings, working patterns, and a repeatable template for scaling up the migration across the rest of your front-end.

Final Thoughts

Modernizing a legacy front-end application is not a one-time effort—it’s a journey of continuous architectural evolution. By embracing a gradual, strategy-led migration to Next.js, you sidestep the high-risk gamble of a full rewrite and instead gain control, flexibility, and momentum.

This migration isn’t just about adopting new tools—it’s about shifting your engineering culture toward modularity, maintainability, and resilience. With clear migration phases, smart tooling like reverse proxies, and a shared foundation of components and standards, you empower your teams to deliver value incrementally—without halting product progress.

The key is to think like a system designer: architect for coexistence, invest in shared infrastructure, and validate every step with a working proof of concept. Migration success lies not in technical perfection, but in sustainable progress.

If done right, you'll not only end up with a modern stack—but with a stronger, faster-moving engineering organization ready for the next decade of front-end development.